feat(examples): switch webauthn ceremony examples to ReqwestRelatedOriginsClient

Using NoRelatedOriginsClient in the bundled examples taught readers the
wrong default. Wire up the reqwest-backed convenience client instead,
gate the three webauthn ceremony examples on the related-origins-client
feature, and update the README run commands.

Also re-exports HttpPolicy and ReqwestRelatedOriginsClient at
ops::webauthn so examples import from a single path.

Author: AlfioEmanueleFresta

README.md

@@ -67,15 +67,17 @@ $ git submodule update --init
 The basic ceremony examples (register + authenticate) cover all transports. The
 WebAuthn examples consume and emit JSON per the [WebAuthn IDL][webauthn].
 
-| Transport             | FIDO U2F                                                                                                                 | WebAuthn (FIDO2)                                                                                                                   |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
-| **USB (HID)**         | `cargo run --example u2f_hid`                                                                                            | `cargo run --example webauthn_hid`                                                                                                 |
-| **Bluetooth (BLE)**   | `cargo run --example u2f_ble`                                                                                            | —                                                                                                                                  |
-| **NFC** [^nfc]        | `cargo run --features nfc-backend-pcsc --example u2f_nfc`<br>`cargo run --features nfc-backend-libnfc --example u2f_nfc` | `cargo run --features nfc-backend-pcsc --example webauthn_nfc`<br>`cargo run --features nfc-backend-libnfc --example webauthn_nfc` |
-| **Hybrid (caBLE v2)** | —                                                                                                                        | `cargo run --example webauthn_cable`                                                                                               |
+| Transport             | FIDO U2F                                                                                                                 | WebAuthn (FIDO2) [^ro]                                                                                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **USB (HID)**         | `cargo run --example u2f_hid`                                                                                            | `cargo run --features related-origins-client --example webauthn_hid`                                                                                                         |
+| **Bluetooth (BLE)**   | `cargo run --example u2f_ble`                                                                                            | —                                                                                                                                                                            |
+| **NFC** [^nfc]        | `cargo run --features nfc-backend-pcsc --example u2f_nfc`<br>`cargo run --features nfc-backend-libnfc --example u2f_nfc` | `cargo run --features nfc-backend-pcsc,related-origins-client --example webauthn_nfc`<br>`cargo run --features nfc-backend-libnfc,related-origins-client --example webauthn_nfc` |
+| **Hybrid (caBLE v2)** | —                                                                                                                        | `cargo run --features related-origins-client --example webauthn_cable`                                                                                                       |
 
 [^nfc]: `nfc-backend-pcsc` is pure userspace and recommended on most systems. `nfc-backend-libnfc` requires the `libnfc` system library. Both can be enabled together; the first FIDO device found by either backend is used.
 
+[^ro]: The WebAuthn ceremony examples wire up the bundled reqwest-backed [related-origins](https://www.w3.org/TR/webauthn-3/#sctn-related-origins) client, which lives behind the optional `related-origins-client` feature. Consumers that already ship their own HTTP stack can implement `RelatedOriginsHttpClient` directly and omit the feature.
+
 Additional HID-only examples cover specific FIDO2 features and authenticator management:
 
 ```

libwebauthn/Cargo.toml

@@ -125,15 +125,17 @@ required-features = ["nfc"]
 [[example]]
 name = "webauthn_hid"
 path = "examples/ceremony/webauthn_hid.rs"
+required-features = ["related-origins-client"]
 
 [[example]]
 name = "webauthn_nfc"
 path = "examples/ceremony/webauthn_nfc.rs"
-required-features = ["nfc"]
+required-features = ["nfc", "related-origins-client"]
 
 [[example]]
 name = "webauthn_cable"
 path = "examples/ceremony/webauthn_cable.rs"
+required-features = ["related-origins-client"]
 
 [[example]]
 name = "webauthn_extensions_hid"

libwebauthn/examples/ceremony/webauthn_cable.rs

@@ -12,8 +12,9 @@ use qrcode::QrCode;
 use tokio::time::sleep;
 
 use libwebauthn::ops::webauthn::{
-    GetAssertionRequest, JsonFormat, MakeCredentialRequest, NoRelatedOriginsClient, RequestOrigin,
-    SystemPublicSuffixList, WebAuthnIDL as _, WebAuthnIDLResponse as _,
+    GetAssertionRequest, JsonFormat, MakeCredentialRequest, RequestOrigin,
+    ReqwestRelatedOriginsClient, SystemPublicSuffixList, WebAuthnIDL as _,
+    WebAuthnIDLResponse as _,
 };
 use libwebauthn::transport::{Channel as _, Device};
 use libwebauthn::webauthn::WebAuthn;
@@ -69,6 +70,7 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
     let psl = SystemPublicSuffixList::auto().expect(
         "PSL not available; install the publicsuffix-list (or publicsuffix-list-dafsa) package, or pass an explicit path",
     );
+    let related_origins = ReqwestRelatedOriginsClient::new()?;
 
     {
         let mut device: CableQrCodeDevice = CableQrCodeDevice::new_persistent(
@@ -94,7 +96,7 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
         let request = MakeCredentialRequest::from_json(
             &request_origin,
             &psl,
-            &NoRelatedOriginsClient,
+            &related_origins,
             MAKE_CREDENTIAL_REQUEST,
         )
         .await
@@ -131,7 +133,7 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
     let request = GetAssertionRequest::from_json(
         &request_origin,
         &psl,
-        &NoRelatedOriginsClient,
+        &related_origins,
         GET_ASSERTION_REQUEST,
     )
     .await

libwebauthn/examples/ceremony/webauthn_hid.rs

@@ -2,8 +2,9 @@ use std::error::Error;
 use std::time::Duration;
 
 use libwebauthn::ops::webauthn::{
-    GetAssertionRequest, JsonFormat, MakeCredentialRequest, NoRelatedOriginsClient, RequestOrigin,
-    SystemPublicSuffixList, WebAuthnIDL as _, WebAuthnIDLResponse as _,
+    GetAssertionRequest, JsonFormat, MakeCredentialRequest, RequestOrigin,
+    ReqwestRelatedOriginsClient, SystemPublicSuffixList, WebAuthnIDL as _,
+    WebAuthnIDLResponse as _,
 };
 use libwebauthn::proto::ctap2::Ctap2PublicKeyCredentialDescriptor;
 use libwebauthn::transport::hid::list_devices;
@@ -32,6 +33,7 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
         let psl = SystemPublicSuffixList::auto().expect(
             "PSL not available; install the publicsuffix-list (or publicsuffix-list-dafsa) package, or pass an explicit path",
         );
+        let related_origins = ReqwestRelatedOriginsClient::new()?;
         let request_json = r#"
                 {
                     "rp": {
@@ -56,14 +58,10 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
                     "attestation": "none"
                 }
                 "#;
-        let make_credentials_request: MakeCredentialRequest = MakeCredentialRequest::from_json(
-            &request_origin,
-            &psl,
-            &NoRelatedOriginsClient,
-            request_json,
-        )
-        .await
-        .expect("Failed to parse request JSON");
+        let make_credentials_request: MakeCredentialRequest =
+            MakeCredentialRequest::from_json(&request_origin, &psl, &related_origins, request_json)
+                .await
+                .expect("Failed to parse request JSON");
         println!(
             "WebAuthn MakeCredential request: {:?}",
             make_credentials_request
@@ -105,14 +103,10 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
                 }}
                 "#
         );
-        let get_assertion: GetAssertionRequest = GetAssertionRequest::from_json(
-            &request_origin,
-            &psl,
-            &NoRelatedOriginsClient,
-            &request_json,
-        )
-        .await
-        .expect("Failed to parse request JSON");
+        let get_assertion: GetAssertionRequest =
+            GetAssertionRequest::from_json(&request_origin, &psl, &related_origins, &request_json)
+                .await
+                .expect("Failed to parse request JSON");
         println!("WebAuthn GetAssertion request: {:?}", get_assertion);
 
         let response = retry_user_errors!(channel.webauthn_get_assertion(&get_assertion)).unwrap();

libwebauthn/examples/ceremony/webauthn_nfc.rs

@@ -1,8 +1,9 @@
 use std::error::Error;
 
 use libwebauthn::ops::webauthn::{
-    GetAssertionRequest, JsonFormat, MakeCredentialRequest, NoRelatedOriginsClient, RequestOrigin,
-    SystemPublicSuffixList, WebAuthnIDL as _, WebAuthnIDLResponse as _,
+    GetAssertionRequest, JsonFormat, MakeCredentialRequest, RequestOrigin,
+    ReqwestRelatedOriginsClient, SystemPublicSuffixList, WebAuthnIDL as _,
+    WebAuthnIDLResponse as _,
 };
 use libwebauthn::transport::nfc::{get_nfc_device, is_nfc_available};
 use libwebauthn::transport::{Channel as _, Device};
@@ -30,10 +31,11 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
     let psl = SystemPublicSuffixList::auto().expect(
         "PSL not available; install the publicsuffix-list (or publicsuffix-list-dafsa) package, or pass an explicit path",
     );
+    let related_origins = ReqwestRelatedOriginsClient::new()?;
     let make_credentials_request = MakeCredentialRequest::from_json(
         &request_origin,
         &psl,
-        &NoRelatedOriginsClient,
+        &related_origins,
         r#"
         {
             "rp": {
@@ -79,7 +81,7 @@ pub async fn main() -> Result<(), Box<dyn Error>> {
     let get_assertion = GetAssertionRequest::from_json(
         &request_origin,
         &psl,
-        &NoRelatedOriginsClient,
+        &related_origins,
         r#"
         {
             "challenge": "Y3JlZGVudGlhbHMtZm9yLWxpbnV4L2xpYndlYmF1dGhu",

libwebauthn/src/ops/webauthn/mod.rs

@@ -40,6 +40,8 @@ pub use related_origins::{
     validate_related_origins, NoRelatedOriginsClient, RelatedOriginsError,
     RelatedOriginsHttpClient, WellKnownResponse,
 };
+#[cfg(feature = "related-origins-client")]
+pub use related_origins::{HttpPolicy, ReqwestRelatedOriginsClient};
 use serde::Deserialize;
 
 #[derive(Debug, Clone, Copy, Deserialize, PartialEq)]