refactor(webauthn): narrow RelatedOriginsHttpClient error to WellKnownFetchError

AlfioEmanueleFresta · AlfioEmanueleFresta · commit 2a4d4e5dc1d9 · 2026-05-18T20:05:21.000+01:00
The trait's old return type was the full RelatedOriginsError, but four of
its five variants (UnexpectedContentType, MalformedJson, MalformedDocument,
NoMatchingOrigin) are produced inside validate_related_origins after the
fetch returns. Implementers had no reason to ever emit them.

Introduce WellKnownFetchError with the variants a fetcher can actually
emit (Transport, Status, BodyTooLarge, NotSupported) and let
RelatedOriginsError wrap it via a Fetch variant with #[from]. The reqwest
client now distinguishes non-200 status from transport faults and from
body-cap hits without stringifying everything.

Also drops RelatedOriginsError::kind(); the two debug! call sites switch
to logging the Display form of the error directly.
diff --git a/libwebauthn/src/ops/webauthn/get_assertion.rs b/libwebauthn/src/ops/webauthn/get_assertion.rs
@@ -187,7 +187,7 @@ impl FromIdlModel<PublicKeyCredentialRequestOptionsJSON, GetAssertionRequestPars
                 if let Err(err) =
                     validate_related_origins(&request_origin.origin, &parsed, psl, http).await
                 {
-                    debug!(rp_id = %parsed.0, kind = err.kind(), "Related-origins validation failed");
+                    debug!(rp_id = %parsed.0, %err, "Related-origins validation failed");
                     return Err(GetAssertionRequestParsingError::MismatchingRelyingPartyId(
                         parsed.0,
                         effective_rp_id.to_string(),
@@ -664,7 +664,7 @@ mod tests {
 
     use crate::ops::webauthn::psl::MockPublicSuffixList;
     use crate::ops::webauthn::related_origins::{
-        RelatedOriginsError, RelatedOriginsHttpClient, WellKnownResponse,
+        RelatedOriginsHttpClient, WellKnownFetchError, WellKnownResponse,
     };
     use crate::ops::webauthn::{GetAssertionRequest, NoRelatedOriginsClient, RequestOrigin};
     use crate::proto::ctap2::Ctap2PublicKeyCredentialType;
@@ -674,7 +674,7 @@ mod tests {
     /// Test-only HTTP client backed by a fixed response. `panicking` proves the
     /// suffix-check short-circuit by failing the test if the fetch is invoked.
     struct MockHttpClient {
-        response: Option<Result<WellKnownResponse, RelatedOriginsError>>,
+        response: Option<Result<WellKnownResponse, WellKnownFetchError>>,
     }
 
     impl MockHttpClient {
@@ -687,7 +687,7 @@ mod tests {
             }
         }
 
-        fn err(e: RelatedOriginsError) -> Self {
+        fn err(e: WellKnownFetchError) -> Self {
             Self {
                 response: Some(Err(e)),
             }
@@ -703,7 +703,7 @@ mod tests {
         async fn fetch_well_known(
             &self,
             _: &RelyingPartyId,
-        ) -> Result<WellKnownResponse, RelatedOriginsError> {
+        ) -> Result<WellKnownResponse, WellKnownFetchError> {
             match &self.response {
                 Some(r) => r.clone(),
                 None => panic!("fetch_well_known should not be called"),
@@ -912,7 +912,7 @@ mod tests {
     async fn related_origins_fetch_error_keeps_mismatch_error() {
         let request_origin: RequestOrigin = "https://app.example.org".parse().unwrap();
         let req_json = json_field_add(REQUEST_BASE_JSON, "rpId", r#""example.com""#);
-        let http = MockHttpClient::err(RelatedOriginsError::FetchFailed("simulated".into()));
+        let http = MockHttpClient::err(WellKnownFetchError::Transport("simulated".into()));
 
         let result = GetAssertionRequest::from_json(
             &request_origin,
diff --git a/libwebauthn/src/ops/webauthn/make_credential.rs b/libwebauthn/src/ops/webauthn/make_credential.rs
@@ -401,7 +401,7 @@ impl FromIdlModel<PublicKeyCredentialCreationOptionsJSON, MakeCredentialRequestP
             if let Err(err) =
                 validate_related_origins(&request_origin.origin, &rp_id, psl, http).await
             {
-                debug!(rp_id = %rp_id.0, kind = err.kind(), "Related-origins validation failed");
+                debug!(rp_id = %rp_id.0, %err, "Related-origins validation failed");
                 return Err(
                     MakeCredentialRequestParsingError::MismatchingRelyingPartyId(
                         rp_id.0,
@@ -719,7 +719,7 @@ mod tests {
 
     use crate::ops::webauthn::psl::MockPublicSuffixList;
     use crate::ops::webauthn::related_origins::{
-        RelatedOriginsError, RelatedOriginsHttpClient, WellKnownResponse,
+        RelatedOriginsHttpClient, WellKnownFetchError, WellKnownResponse,
     };
     use crate::ops::webauthn::{MakeCredentialRequest, NoRelatedOriginsClient, RequestOrigin};
     use crate::proto::ctap2::Ctap2PublicKeyCredentialType;
@@ -729,7 +729,7 @@ mod tests {
     /// Test-only HTTP client backed by a fixed response. `panicking` proves the
     /// suffix-check short-circuit by failing the test if the fetch is invoked.
     struct MockHttpClient {
-        response: Option<Result<WellKnownResponse, RelatedOriginsError>>,
+        response: Option<Result<WellKnownResponse, WellKnownFetchError>>,
     }
 
     impl MockHttpClient {
@@ -742,7 +742,7 @@ mod tests {
             }
         }
 
-        fn err(e: RelatedOriginsError) -> Self {
+        fn err(e: WellKnownFetchError) -> Self {
             Self {
                 response: Some(Err(e)),
             }
@@ -758,7 +758,7 @@ mod tests {
         async fn fetch_well_known(
             &self,
             _: &RelyingPartyId,
-        ) -> Result<WellKnownResponse, RelatedOriginsError> {
+        ) -> Result<WellKnownResponse, WellKnownFetchError> {
             match &self.response {
                 Some(r) => r.clone(),
                 None => panic!("fetch_well_known should not be called"),
@@ -1262,7 +1262,7 @@ mod tests {
             "rp",
             r#"{"id": "example.com", "name": "example.com"}"#,
         );
-        let http = MockHttpClient::err(RelatedOriginsError::FetchFailed("simulated".into()));
+        let http = MockHttpClient::err(WellKnownFetchError::Transport("simulated".into()));
 
         let result = MakeCredentialRequest::from_json(
             &request_origin,
diff --git a/libwebauthn/src/ops/webauthn/mod.rs b/libwebauthn/src/ops/webauthn/mod.rs
@@ -39,7 +39,7 @@ pub use psl::{
 };
 pub use related_origins::{
     validate_related_origins, NoRelatedOriginsClient, RelatedOriginsError,
-    RelatedOriginsHttpClient, WellKnownResponse,
+    RelatedOriginsHttpClient, WellKnownFetchError, WellKnownResponse,
 };
 #[cfg(feature = "related-origins-client")]
 pub use related_origins::{HttpPolicy, ReqwestRelatedOriginsClient};
diff --git a/libwebauthn/src/ops/webauthn/related_origins/http.rs b/libwebauthn/src/ops/webauthn/related_origins/http.rs
@@ -8,7 +8,7 @@ use futures::StreamExt;
 use reqwest::redirect::Policy;
 use reqwest::{Client, StatusCode};
 
-use super::{RelatedOriginsError, RelatedOriginsHttpClient, WellKnownResponse};
+use super::{RelatedOriginsHttpClient, WellKnownFetchError, WellKnownResponse};
 use crate::ops::webauthn::idl::rpid::RelyingPartyId;
 
 #[derive(Debug, Clone)]
@@ -35,11 +35,11 @@ pub struct ReqwestRelatedOriginsClient {
 }
 
 impl ReqwestRelatedOriginsClient {
-    pub fn new() -> Result<Self, RelatedOriginsError> {
+    pub fn new() -> Result<Self, WellKnownFetchError> {
         Self::with_policy(HttpPolicy::default())
     }
 
-    pub fn with_policy(policy: HttpPolicy) -> Result<Self, RelatedOriginsError> {
+    pub fn with_policy(policy: HttpPolicy) -> Result<Self, WellKnownFetchError> {
         let max_redirects = policy.max_redirects;
         let redirect_policy = Policy::custom(move |attempt| {
             if attempt.previous().len() >= max_redirects {
@@ -58,7 +58,7 @@ impl ReqwestRelatedOriginsClient {
             .referer(false)
             .timeout(policy.request_timeout)
             .build()
-            .map_err(|e| RelatedOriginsError::FetchFailed(e.to_string()))?;
+            .map_err(|e| WellKnownFetchError::Transport(e.to_string()))?;
         Ok(Self {
             client,
             max_body_bytes: policy.max_body_bytes,
@@ -71,19 +71,16 @@ impl RelatedOriginsHttpClient for ReqwestRelatedOriginsClient {
     async fn fetch_well_known(
         &self,
         rp_id: &RelyingPartyId,
-    ) -> Result<WellKnownResponse, RelatedOriginsError> {
+    ) -> Result<WellKnownResponse, WellKnownFetchError> {
         let url = format!("https://{}/.well-known/webauthn", rp_id.0);
         let response = self
             .client
             .get(&url)
             .send()
             .await
-            .map_err(|e| RelatedOriginsError::FetchFailed(e.to_string()))?;
+            .map_err(|e| WellKnownFetchError::Transport(e.to_string()))?;
         if response.status() != StatusCode::OK {
-            return Err(RelatedOriginsError::FetchFailed(format!(
-                "status {}",
-                response.status()
-            )));
+            return Err(WellKnownFetchError::Status(response.status().as_u16()));
         }
         let content_type = response
             .headers()
@@ -94,11 +91,9 @@ impl RelatedOriginsHttpClient for ReqwestRelatedOriginsClient {
         let mut body = Vec::with_capacity(8 * 1024);
         let mut stream = response.bytes_stream();
         while let Some(chunk) = stream.next().await {
-            let chunk = chunk.map_err(|e| RelatedOriginsError::FetchFailed(e.to_string()))?;
+            let chunk = chunk.map_err(|e| WellKnownFetchError::Transport(e.to_string()))?;
             if body.len() + chunk.len() > self.max_body_bytes {
-                return Err(RelatedOriginsError::FetchFailed(
-                    "body exceeded size cap".into(),
-                ));
+                return Err(WellKnownFetchError::BodyTooLarge);
             }
             body.extend_from_slice(&chunk);
         }
diff --git a/libwebauthn/src/ops/webauthn/related_origins/mod.rs b/libwebauthn/src/ops/webauthn/related_origins/mod.rs
@@ -32,22 +32,41 @@ pub struct WellKnownResponse {
 /// Fetcher for `https://{rp_id}/.well-known/webauthn`, per WebAuthn L3 §5.11.1
 /// step 2. Implementations MUST send no credentials, no Referer, refuse
 /// non-`https://` redirects, cap the body size, and bound the request duration.
-/// Implementations MUST return `Err(FetchFailed)` for any status code other
-/// than 200 (after following redirects). Implementations MUST report the wire
-/// `Content-Type` header value unmodified (or `None` if absent) and MUST NOT
-/// synthesise an `application/json` content type for non-JSON responses.
+/// Implementations MUST return `Err(WellKnownFetchError::Status)` for any
+/// status code other than 200 (after following redirects). Implementations MUST
+/// report the wire `Content-Type` header value unmodified (or `None` if absent)
+/// and MUST NOT synthesise an `application/json` content type for non-JSON
+/// responses.
 #[async_trait]
 pub trait RelatedOriginsHttpClient: Send + Sync {
     async fn fetch_well_known(
         &self,
         rp_id: &RelyingPartyId,
-    ) -> Result<WellKnownResponse, RelatedOriginsError>;
+    ) -> Result<WellKnownResponse, WellKnownFetchError>;
+}
+
+/// Failure modes for [`RelatedOriginsHttpClient::fetch_well_known`].
+#[derive(thiserror::Error, Debug, Clone)]
+pub enum WellKnownFetchError {
+    /// Transport-level failure: TLS, DNS, timeout, rejected redirect, body
+    /// stream interrupt, client build error, etc.
+    #[error("transport error: {0}")]
+    Transport(String),
+    /// Endpoint replied with a non-200 status (after following redirects).
+    #[error("HTTP status {0}")]
+    Status(u16),
+    /// Body exceeded the implementation's configured size cap before completion.
+    #[error("body exceeded configured size cap")]
+    BodyTooLarge,
+    /// Implementation does not perform fetches (see [`NoRelatedOriginsClient`]).
+    #[error("client does not support related-origin fetches")]
+    NotSupported,
 }
 
 #[derive(thiserror::Error, Debug, Clone)]
 pub enum RelatedOriginsError {
     #[error("well-known fetch failed: {0}")]
-    FetchFailed(String),
+    Fetch(#[from] WellKnownFetchError),
     #[error("unexpected content type: {0:?}")]
     UnexpectedContentType(Option<String>),
     /// Step 2.b: body did not decode as JSON.
@@ -60,19 +79,6 @@ pub enum RelatedOriginsError {
     NoMatchingOrigin,
 }
 
-impl RelatedOriginsError {
-    /// Log-safe variant discriminant; `Debug`/`Display` may carry reqwest/serde text with IPs or body snippets.
-    pub fn kind(&self) -> &'static str {
-        match self {
-            RelatedOriginsError::FetchFailed(_) => "fetch_failed",
-            RelatedOriginsError::UnexpectedContentType(_) => "unexpected_content_type",
-            RelatedOriginsError::MalformedJson(_) => "malformed_json",
-            RelatedOriginsError::MalformedDocument(_) => "malformed_document",
-            RelatedOriginsError::NoMatchingOrigin => "no_matching_origin",
-        }
-    }
-}
-
 pub type RelatedOriginsResult = Result<(), RelatedOriginsError>;
 
 #[derive(Debug, Deserialize)]
@@ -192,10 +198,8 @@ impl RelatedOriginsHttpClient for NoRelatedOriginsClient {
     async fn fetch_well_known(
         &self,
         _: &RelyingPartyId,
-    ) -> Result<WellKnownResponse, RelatedOriginsError> {
-        Err(RelatedOriginsError::FetchFailed(
-            "this client does not support related origin requests".into(),
-        ))
+    ) -> Result<WellKnownResponse, WellKnownFetchError> {
+        Err(WellKnownFetchError::NotSupported)
     }
 }
 
@@ -205,15 +209,15 @@ mod tests {
     use super::*;
 
     struct MockClient {
-        response: Result<WellKnownResponse, RelatedOriginsError>,
+        response: Result<WellKnownResponse, WellKnownFetchError>,
     }
 
     #[async_trait]
     impl RelatedOriginsHttpClient for MockClient {
         async fn fetch_well_known(
             &self,
             _: &RelyingPartyId,
-        ) -> Result<WellKnownResponse, RelatedOriginsError> {
+        ) -> Result<WellKnownResponse, WellKnownFetchError> {
             self.response.clone()
         }
     }
@@ -670,9 +674,9 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn fetch_error_propagates_as_fetch_failed() {
+    async fn fetch_error_propagates_as_fetch() {
         let http = MockClient {
-            response: Err(RelatedOriginsError::FetchFailed("simulated".into())),
+            response: Err(WellKnownFetchError::Transport("simulated".into())),
         };
         let res = validate_related_origins(
             &caller("https://example.com"),
@@ -681,7 +685,12 @@ mod tests {
             &http,
         )
         .await;
-        assert!(matches!(res, Err(RelatedOriginsError::FetchFailed(_))));
+        assert!(matches!(
+            res,
+            Err(RelatedOriginsError::Fetch(WellKnownFetchError::Transport(
+                _
+            )))
+        ));
     }
 
     #[tokio::test]
diff --git a/libwebauthn/tests/related_origins.rs b/libwebauthn/tests/related_origins.rs
@@ -6,8 +6,8 @@
 use async_trait::async_trait;
 
 use libwebauthn::ops::webauthn::{
-    GetAssertionRequest, MakeCredentialRequest, PublicSuffixList, RelatedOriginsError,
-    RelatedOriginsHttpClient, RelyingPartyId, RequestOrigin, WebAuthnIDL, WellKnownResponse,
+    GetAssertionRequest, MakeCredentialRequest, PublicSuffixList, RelatedOriginsHttpClient,
+    RelyingPartyId, RequestOrigin, WebAuthnIDL, WellKnownFetchError, WellKnownResponse,
 };
 
 const KNOWN_SUFFIXES: &[&str] = &["com", "org"];
@@ -39,7 +39,7 @@ impl RelatedOriginsHttpClient for StaticHttp {
     async fn fetch_well_known(
         &self,
         _: &RelyingPartyId,
-    ) -> Result<WellKnownResponse, RelatedOriginsError> {
+    ) -> Result<WellKnownResponse, WellKnownFetchError> {
         Ok(WellKnownResponse {
             content_type: Some("application/json".into()),
             body: self.body.as_bytes().to_vec(),
